/*
 *   The contents of this file are subject to the Mozilla Public License
 *   Version 1.1 (the "License"); you may not use this file except in
 *   compliance with the License. You may obtain a copy of the License at
 *   http://www.mozilla.org/MPL/
 *
 *   Software distributed under the License is distributed on an "AS IS"
 *   basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 *   License for the specific language governing rights and limitations
 *   under the License.
 *
 *   The Original Code is Matra - the DTD Parser.
 *
 *   The Initial Developer of the Original Code is Conrad S Roche.
 *   Portions created by Conrad S Roche are Copyright (C) Conrad 
 *   S Roche. All Rights Reserved.
 *
 *   Alternatively, the contents of this file may be used under the terms
 *   of the GNU GENERAL PUBLIC LICENSE Version 2 or any later version
 *   (the  "[GPL] License"), in which case the
 *   provisions of GPL License are applicable instead of those
 *   above.  If you wish to allow use of your version of this file only
 *   under the terms of the GPL License and not to allow others to use
 *   your version of this file under the MPL, indicate your decision by
 *   deleting  the provisions above and replace  them with the notice and
 *   other provisions required by the GPL License.  If you do not delete
 *   the provisions above, a recipient may use your version of this file
 *   under either the MPL or the GPL License."
 *
 *   [NOTE: The text of this Exhibit A may differ slightly from the text of
 *   the notices in the Source Code files of the Original Code. You should
 *   use the text of this Exhibit A rather than the text found in the
 *   Original Code Source Code for Your Modifications.]
 *
 * Created: Conrad S Roche <derupe at users.sourceforge.net>,  21-Sep-2003
 */
package com.conradroche.dtd.decl.elem;

/**
 * The ContentParticle. 
 * <p/>
 * From the XML Specifications -
 * <br/>
 * content particles (cps), consist of names, choice lists of content 
 * particles, or sequence lists of content particles.
 * 
 * [48]    cp    ::=    (Name | choice | seq) ('?' | '*' | '+')? 
 *
 * @author Conrad Roche
 */
public interface ContentParticle {

	/*
	 * From the XML Specifications [Section 3.2.1 Element Content]
	 * 
	 * 	The optional character following a name or list governs 
	 * 	whether the element or the content particles in the list 
	 * 	may occur one or more (+), zero or more (*), or zero or 
	 * 	one times (?). The absence of such an operator means that 
	 * 	the element or content particle must appear exactly once.
	 */

	/**
	 * Constant to denote and optional cardinality.
	 */
	public static final short CARDINALITY_OPTIONAL = 1; // '?'

	/**
	 * Constant to denote and multiple cardinality.
	 */
	public static final short CARDINALITY_MULTIPLE = 2; // '+'

	/**
	 * Constant to denote and optional multiple cardinality.
	 */
	public static final short CARDINALITY_OPTIONAL_MULTIPLE = 3; // '*'

	/**
	 * Constant to denote and single cardinality.
	 */
	public static final short CARDINALITY_ONCE = 4; // ''
	
	/**
	 * Returns the cardinality for this ContentParticle.
	 * <br/>
	 * The cardinality can have one of four values - 
	 * CARDINALITY_OPTIONAL ('?'), CARDINALITY_MULTIPLE ('+') or
	 * CARDINALITY_OPTIONAL_MULTIPLE ('*') or
	 * CARDINALITY_ONCE.
	 * 
	 * @see #setCardinality
	 * 
	 * @return The cardinality for this ContentParticle.
	 */
	public short getCardinality();
	
	/**
	 * Sets the cardinality for this ContentParticle.
	 * <br/>
	 * The cardinality can have one of four values - 
	 * CARDINALITY_OPTIONAL ('?'), CARDINALITY_MULTIPLE ('+') or
	 * CARDINALITY_OPTIONAL_MULTIPLE ('*') or
	 * CARDINALITY_ONCE.
	 * 
	 * @see #getCardinality
	 * 
	 * @param cardinality The cardinality for this ContentParticle.
	 */
	public void setCardinality(short cardinality);
}
